/*
 * Copyright (C) 2023 Huawei Device Co., Ltd.
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * @addtogroup Image_NativeModule
 * @{
 *
 * @brief 提供图片处理的相关能力，包括图片编解码、从Native层获取图片数据等。\n
 * 
 * 使用该模块的接口，无需通过JS接口导入，可直接使用NDK完成功能开发。
 * @since 12
 */

/**
 * @file image_packer_native.h
 *
 * @brief 图片编码API。
 *
 * @library libimage_packer.so
 * @kit ImageKit
 * @include <multimedia/image_framework/image/image_packer_native.h>
 * @syscap SystemCapability.Multimedia.Image.ImagePacker
 * @since 12
 */

#ifndef INTERFACES_KITS_NATIVE_INCLUDE_IMAGE_IMAGE_PACKER_NATIVE_H_
#define INTERFACES_KITS_NATIVE_INCLUDE_IMAGE_IMAGE_PACKER_NATIVE_H_
#include "image_common.h"
#include "image_source_native.h"
#include "pixelmap_native.h"

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief ImagePacker结构体类型，用于执行ImagePacker相关操作。\n
 * 创建OH_ImagePackerNative对象使用{@link OH_ImagePackerNative_Create}函数。\n
 * 释放OH_ImagePackerNative对象使用{@link OH_ImagePackerNative_Release}函数。
 *
 * @since 12
 */
typedef struct OH_ImagePackerNative OH_ImagePackerNative;

/**
 * @brief OH_PackingOptions是native层封装的图像编码选项结构体，OH_PackingOptions结构体不可直接操作，而是采用函数调用方式创建、释放结构体以及操作具体字段。\n
 * 创建PackingOptions结构体的对象使用{@link OH_PackingOptions_Create}函数。\n
 * 释放OH_PackingOptions对象使用{@link OH_PackingOptions_Release}函数。
 *
 * @since 12
 */
typedef struct OH_PackingOptions OH_PackingOptions;

/**
 * @brief OH_PackingOptions是native层封装的图像编码选项结构体，OH_PackingOptions结构体不可直接操作，而是采用函数调用方式创建、释放结构体以及操作具体字段。
 *
 * @since 18
 */
typedef struct OH_PackingOptionsForSequence OH_PackingOptionsForSequence;

/**
 * @brief 编码指定动态范围。
 *
 * @since 12
 */
typedef enum {
    /*
    * 编码动态范围根据图像信息自适应。
    */
    IMAGE_PACKER_DYNAMIC_RANGE_AUTO = 0,
    /*
    * 编码图片为标准动态范围。
    */
    IMAGE_PACKER_DYNAMIC_RANGE_SDR = 1,
} IMAGE_PACKER_DYNAMIC_RANGE;

/**
 * @brief 创建PackingOptions结构体的指针。
 *
 * @param options 用于操作的PackingOptions指针。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 12
 */
Image_ErrorCode OH_PackingOptions_Create(OH_PackingOptions **options);

/**
 * @brief 获取MIME类型。
 *
 * @param options 被操作的OH_PackingOptions指针。
 * @param format 图像格式。可传入一个空指针和零大小，系统将分配内存，但必须在使用后释放内存。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 12
 */
Image_ErrorCode OH_PackingOptions_GetMimeType(OH_PackingOptions *options,
    Image_MimeType *format);

/**
 * @brief  获取编解码参数中的MIME类型。输出的format.data以字符串结束符结尾。
 *
 * @param options 编码参数指针。
 * @param format 编码参数中的MIME类型的指针。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_PACKER_INVALID_PARAMETER：options或format为空。
 * @since 19
 */
Image_ErrorCode OH_PackingOptions_GetMimeTypeWithNull(OH_PackingOptions *options,
    Image_MimeType *format);

/**
 * @brief 设置MIME类型。
 *
 * @param options 被操作的OH_PackingOptions指针。
 * @param format 图像格式。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 12
 */
Image_ErrorCode OH_PackingOptions_SetMimeType(OH_PackingOptions *options,
    Image_MimeType *format);

/**
 * @brief 获取编码质量。
 *
 * @param options 被操作的OH_PackingOptions指针。
 * @param quality 编码质量。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 12
 */
Image_ErrorCode OH_PackingOptions_GetQuality(OH_PackingOptions *options,
    uint32_t *quality);

/**
 * @brief 设置编码质量。
 *
 * @param options 被操作的OH_PackingOptions指针。
 * @param quality 编码质量。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 12
 */
Image_ErrorCode OH_PackingOptions_SetQuality(OH_PackingOptions *options,
    uint32_t quality);

/**
 * @brief 获取OH_PackingOptions结构体的needsPackProperties参数。
 *
 * @param options 被操作的OH_PackingOptions指针。
 * @param needsPackProperties 是否需要编码图片属性信息，例如EXIF。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 12
 */
 Image_ErrorCode OH_PackingOptions_GetNeedsPackProperties(OH_PackingOptions *options,
    bool *needsPackProperties);

/**
 * @brief 设置OH_PackingOptions结构体的needsPackProperties参数。
 *
 * @param options 被操作的OH_PackingOptions指针。
 * @param needsPackProperties 是否需要编码图片属性信息，例如EXIF。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 12
 */
Image_ErrorCode OH_PackingOptions_SetNeedsPackProperties(OH_PackingOptions *options,
    bool needsPackProperties);

/**
 * @brief 获取编码时期望的图片动态范围。
 *
 * @param options 被操作的OH_PackingOptions指针。
 * @param desiredDynamicRange 期望的动态范围{@link IMAGE_PACKER_DYNAMIC_RANGE}。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 12
 */
Image_ErrorCode OH_PackingOptions_GetDesiredDynamicRange(OH_PackingOptions *options, int32_t* desiredDynamicRange);

/**
 * @brief 设置编码时期望的图片动态范围。
 *
 * @param options 被操作的OH_PackingOptions指针。
 * @param desiredDynamicRange 期望的动态范围{@link IMAGE_PACKER_DYNAMIC_RANGE}。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 12
 */
Image_ErrorCode OH_PackingOptions_SetDesiredDynamicRange(OH_PackingOptions *options, int32_t desiredDynamicRange);

/**
 * @brief 释放OH_PackingOptions指针。
 *
 * @param options 被操作的OH_PackingOptions指针。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 12
 */
Image_ErrorCode OH_PackingOptions_Release(OH_PackingOptions *options);

/**
 * @brief 创建OH_PackingOptionsForSequence结构体的指针。
 *
 * @param options 用于操作的OH_PackingOptionsForSequence指针。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 13
 */
Image_ErrorCode OH_PackingOptionsForSequence_Create(OH_PackingOptionsForSequence **options);

/**
 * @brief 设置编码时指定的帧数。
 *
 * @param options 用于操作的OH_PackingOptionsForSequence指针。
 * @param frameCount 图片的帧数。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 13
 */
Image_ErrorCode OH_PackingOptionsForSequence_SetFrameCount(OH_PackingOptionsForSequence *options,
    uint32_t frameCount);

/**
 * @brief 获取编码时指定的帧数。
 *
 * @param options 用于操作的OH_PackingOptionsForSequence指针。
 * @param frameCount 图片的帧数。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 13
 */
Image_ErrorCode OH_PackingOptionsForSequence_GetFrameCount(OH_PackingOptionsForSequence *options,
    uint32_t *frameCount);

/**
 * @brief 设定编码时图片的延迟时间数组。
 *
 * @param options 用于操作的OH_PackingOptionsForSequence指针。
 * @param delayTimeList 图片延迟时间数组的指针。
 * @param delayTimeListLength 图片延迟时间数组的长度。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 13
 */
Image_ErrorCode OH_PackingOptionsForSequence_SetDelayTimeList(OH_PackingOptionsForSequence *options,
    int32_t *delayTimeList, size_t delayTimeListLength);

/**
 * @brief 获取编码时图片的延迟时间数组。
 *
 * @param options 用于操作的OH_PackingOptionsForSequence指针。
 * @param delayTimeList 图片延迟时间数组的指针。
 * @param delayTimeListLength 图片延迟时间数组的长度。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 13
 */
Image_ErrorCode OH_PackingOptionsForSequence_GetDelayTimeList(OH_PackingOptionsForSequence *options,
    int32_t *delayTimeList, size_t delayTimeListLength);

/**
 * @brief 设定编码时图片的过渡帧模式数组。
 *
 * @param options 用于操作的OH_PackingOptionsForSequence指针。
 * @param disposalTypes 图片过渡帧模式数组的指针。
 * @param disposalTypesLength 图片过渡帧模式数组的指针，图片帧过渡模式的参数，如果长度小于frameCount，不足的部分将使用disposalTypes中的最后一个值进行填充，可取值如下：\n
 *                            0：不需要任何操作。\n
 *                            1：保持图形不变。\n
 *                            2：恢复背景色。\n
 *                            3：恢复到之前的状态。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 13
 */
Image_ErrorCode OH_PackingOptionsForSequence_SetDisposalTypes(OH_PackingOptionsForSequence *options,
    uint32_t *disposalTypes, size_t disposalTypesLength);

/**
 * @brief 获取编码时图片的过渡帧模式数组。
 *
 * @param options 用于操作的OH_PackingOptionsForSequence指针。
 * @param disposalTypes 图片过渡帧模式数组的指针。
 * @param disposalTypesLength 图片过渡帧模式数组的长度。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 13
 */
Image_ErrorCode OH_PackingOptionsForSequence_GetDisposalTypes(OH_PackingOptionsForSequence *options,
    uint32_t *disposalTypes, size_t disposalTypesLength);

/**
 * @brief 设定编码时图片循环播放次数，取值范围为[0，65535]，0表示无限循环；若无此字段，则表示不循环播放。
 *
 * @param options 用于操作的OH_PackingOptionsForSequence指针。
 * @param loopCount 图片循环播放次数。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 13
 */
Image_ErrorCode OH_PackingOptionsForSequence_SetLoopCount(OH_PackingOptionsForSequence *options, uint32_t loopCount);

/**
 * @brief 获取编码时图片循环播放次数。
 *
 * @param options 用于操作的OH_PackingOptionsForSequence指针。
 * @param loopCount 图片循环播放次数。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 13
 */
Image_ErrorCode OH_PackingOptionsForSequence_GetLoopCount(OH_PackingOptionsForSequence *options, uint32_t *loopCount);

/**
 * @brief 释放OH_PackingOptionsForSequence指针。
 *
 * @param options 用于操作的OH_PackingOptionsForSequence指针。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 13
 */
Image_ErrorCode OH_PackingOptionsForSequence_Release(OH_PackingOptionsForSequence *options);

/**
 * @brief 创建OH_ImagePackerNative指针。
 *
 * @param imagePacker 被操作的OH_ImagePackerNative指针。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 12
 */
Image_ErrorCode OH_ImagePackerNative_Create(OH_ImagePackerNative **imagePacker);

/**
 * @brief 将ImageSource编码为指定格式的数据。
 *
 * @param imagePacker 被操作的OH_ImagePackerNative指针。
 * @param options 编码选项参数。
 * @param imageSource 用于编码的image source指针。
 * @param outData 用于存储打包图像输出数据的缓冲区。
 * @param size 用于存储打包图像输出数据的缓冲区大小。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_BAD_PARAMETER：参数错误。\n
 *         IMAGE_DECODE_FAILED：解码失败。\n
 *         IMAGE_ALLOC_FAILED：申请内存失败。\n 
 *         IMAGE_TOO_LARGE：数据或图片过大。\n
 *         IMAGE_UNKNOWN_ERROR：未知错误。
 * @since 12
 */
Image_ErrorCode OH_ImagePackerNative_PackToDataFromImageSource(OH_ImagePackerNative *imagePacker,
    OH_PackingOptions *options, OH_ImageSourceNative *imageSource, uint8_t *outData, size_t *size);

/**
 * @brief 将Pixelmap编码为指定格式的数据。
 *
 * @param imagePacker 被操作的OH_ImagePackerNative指针。
 * @param options 编码选项参数。
 * @param pixelmap 用于编码的Pixelmap指针。
 * @param outData 用于存储打包图像输出数据的缓冲区。
 * @param size 用于存储打包图像输出数据的缓冲区大小。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_BAD_PARAMETER：参数错误。\n
 *         IMAGE_DECODE_FAILED：解码失败。\n
 *         IMAGE_ALLOC_FAILED：申请内存失败。\n 
 *         IMAGE_TOO_LARGE：数据或图片过大。\n
 *         IMAGE_UNKNOWN_ERROR：未知错误。
 * @since 12
 */
Image_ErrorCode OH_ImagePackerNative_PackToDataFromPixelmap(OH_ImagePackerNative *imagePacker,
    OH_PackingOptions *options, OH_PixelmapNative *pixelmap, uint8_t *outData, size_t *size);

/**
 * @brief 将Picture编码为指定格式的数据。
 *
 * @param imagePacker 被操作的OH_ImagePackerNative指针。
 * @param options 编码选项参数。
 * @param picture 用于编码的Picture指针。
 * @param outData 用于存储打包图像输出数据的缓冲区。
 * @param size 用于存储打包图像输出数据的缓冲区大小。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_BAD_PARAMETER：参数错误。\n
 *         IMAGE_DECODE_FAILED：解码失败。
 * @since 13
 */
Image_ErrorCode OH_ImagePackerNative_PackToDataFromPicture(OH_ImagePackerNative *imagePacker,
    OH_PackingOptions *options, OH_PictureNative *picture, uint8_t *outData, size_t *size);

/**
 * @brief 将Pixelmap序列编码为数据。
 *
 * @param imagePacker 被操作的OH_ImagePackerNative指针。
 * @param options 编码选项参数 {@link OH_PackingOptionsForSequence}。
 * @param pixelmapSequence 用于编码的Pixelmap序列指针。
 * @param sequenceLength 用于编码的Pixelmap序列长度。
 * @param outData 用于存储编码后图像输出数据的缓冲区。
 * @param outDataSize 用于存储编码后图像输出数据的缓冲区大小。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_BAD_PARAMETER：参数错误。\n
 *         IMAGE_DECODE_FAILED：解码失败。
 * @since 13
 */
Image_ErrorCode OH_ImagePackerNative_PackToDataFromPixelmapSequence(OH_ImagePackerNative *imagePacker,
    OH_PackingOptionsForSequence *options, OH_PixelmapNative **pixelmapSequence,
    size_t sequenceLength, uint8_t *outData, size_t *outDataSize);

/**
 * @brief 将一个ImageSource编码到文件中。
 *
 * @param imagePacker 被操作的OH_ImagePackerNative指针。
 * @param options 编码选项参数。
 * @param imageSource 用于编码的image source指针。
 * @param fd 可写的文件描述符。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_BAD_PARAMETER：参数错误。\n
 *         IMAGE_DECODE_FAILED：解码失败。\n
 *         IMAGE_UNKNOWN_ERROR：未知错误。
 * @since 12
 */
Image_ErrorCode OH_ImagePackerNative_PackToFileFromImageSource(OH_ImagePackerNative *imagePacker,
    OH_PackingOptions *options, OH_ImageSourceNative *imageSource, int32_t fd);

/**
 * @brief 将一个Pixelmap编码到文件中。
 *
 * @param imagePacker 被操作的OH_ImagePackerNative指针。
 * @param options 编码选项参数。
 * @param pixelmap 用于编码的pixelmap指针。
 * @param fd 可写的文件描述符。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_BAD_PARAMETER：参数错误。\n
 *         IMAGE_DECODE_FAILED：解码失败。\n
 *         IMAGE_UNKNOWN_ERROR：未知错误。
 * @since 12
 */
Image_ErrorCode OH_ImagePackerNative_PackToFileFromPixelmap(OH_ImagePackerNative *imagePacker,
    OH_PackingOptions *options, OH_PixelmapNative *pixelmap, int32_t fd);

/**
 * @brief 将一个Picture编码到文件中。
 *
 * @param imagePacker 被操作的OH_ImagePackerNative指针。
 * @param options 编码选项参数。
 * @param picture 用于编码的picture指针。
 * @param fd 可写的文件描述符。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_BAD_PARAMETER：参数错误。\n
 *         IMAGE_DECODE_FAILED：解码失败。\n
 *         IMAGE_UNKNOWN_ERROR：未知错误。
 * @since 13
 */
Image_ErrorCode OH_ImagePackerNative_PackToFileFromPicture(OH_ImagePackerNative *imagePacker,
    OH_PackingOptions *options, OH_PictureNative *picture, int32_t fd);

/**
  * @brief 将一个Pixelmap序列编码到文件中。
  *
  * @param imagePacker 被操作的OH_ImagePackerNative指针。
  * @param options 编码选项参数 {@link OH_PackingOptionsForSequence}。
  * @param pixelmapSequence 用于编码的Pixelmap序列指针。
  * @param sequenceLength 用于编码的Pixelmap序列长度。
  * @param fd 可写的文件描述符。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_BAD_PARAMETER：参数错误。\n
 *         IMAGE_DECODE_FAILED：解码失败。
  * @since 13
 */
Image_ErrorCode OH_ImagePackerNative_PackToFileFromPixelmapSequence(OH_ImagePackerNative *imagePacker,
    OH_PackingOptionsForSequence *options, OH_PixelmapNative **pixelmapSequence, size_t sequenceLength, int32_t fd);

/**
 * @brief 获取支持编码的图片格式。
 *
 * @param supportedFormats 支持编码的图片格式。
 * @param length 数组长度。
 * @return IMAGE_SUCCESS：操作成功。\n
 *         IMAGE_PACKER_INVALID_PARAMETER：参数异常，supportedFormats或length为空。
 * @since 20
 */
Image_ErrorCode OH_ImagePackerNative_GetSupportedFormats(Image_MimeType **supportedFormats, size_t *length);

/**
 * @brief 释放OH_ImagePackerNative指针。
 *
 * @param imagePacker 被操作的OH_ImagePackerNative指针。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 12
 */
Image_ErrorCode OH_ImagePackerNative_Release(OH_ImagePackerNative *imagePacker);

#ifdef __cplusplus
};
#endif
/* *@} */
#endif // INTERFACES_KITS_NATIVE_INCLUDE_IMAGE_IMAGE_PACKER_NATIVE_H_